package cn.iocoder.yudao.module.reading.service.audio;

import cn.iocoder.yudao.module.reading.controller.app.audio.vo.AudioPlayReqVO;
import cn.iocoder.yudao.module.reading.controller.app.audio.vo.AudioResourceRespVO;
import cn.iocoder.yudao.module.reading.dal.dataobject.audio.AudioResourceDO;

import java.util.List;

/**
 * 音频管理 Service 接口
 *
 * @author 芋道源码
 */
public interface AudioService {

    /**
     * 获得音频资源
     *
     * @param id 编号
     * @return 音频资源
     */
    AudioResourceDO getAudioResource(Long id);

    /**
     * 根据分类获得音频资源列表
     *
     * @param userId   用户ID
     * @param category 音频分类
     * @param language 语言类型（可选）
     * @param limit    限制数量
     * @return 音频资源列表
     */
    List<AudioResourceRespVO> getAudioResourcesByCategory(Long userId, String category, String language, Integer limit);

    /**
     * 搜索音频资源
     *
     * @param userId   用户ID
     * @param keyword  关键词
     * @param language 语言类型（可选）
     * @return 音频资源列表
     */
    List<AudioResourceRespVO> searchAudioResources(Long userId, String keyword, String language);

    /**
     * 获得推荐音频资源
     *
     * @param userId   用户ID
     * @param language 语言类型（可选）
     * @param limit    限制数量
     * @return 音频资源列表
     */
    List<AudioResourceRespVO> getRecommendedAudioResources(Long userId, String language, Integer limit);

    /**
     * 保存音频播放记录
     *
     * @param userId     用户ID
     * @param playReqVO  播放记录信息
     * @return 记录ID
     */
    Long saveAudioPlayRecord(Long userId, AudioPlayReqVO playReqVO);

    /**
     * 获得用户最近播放的音频
     *
     * @param userId 用户ID
     * @param limit  限制数量
     * @return 音频资源列表
     */
    List<AudioResourceRespVO> getRecentPlayAudios(Long userId, Integer limit);

    /**
     * 清空用户播放记录
     *
     * @param userId   用户ID
     * @param category 分类（可选，如果指定则只清空该分类）
     */
    void clearPlayRecords(Long userId, String category);

    /**
     * 删除单个音频播放记录
     *
     * @param userId  用户ID
     * @param audioId 音频ID
     */
    void deletePlayRecord(Long userId, Long audioId);

    /**
     * 根据绘本ID获得相关音频
     *
     * @param userId 用户ID
     * @param bookId 绘本ID
     * @return 音频资源列表
     */
    List<AudioResourceRespVO> getAudiosByBookId(Long userId, Long bookId);

    /**
     * 根据绘本集ID获得相关音频
     *
     * @param userId    用户ID
     * @param bookSetId 绘本集ID
     * @return 音频资源列表
     */
    List<AudioResourceRespVO> getAudiosByBookSetId(Long userId, Long bookSetId);

    /**
     * 获取下一个音频资源ID
     * 用于在创建音频资源之前获得真实ID，避免文件上传时的临时ID问题
     *
     * @return 下一个将要分配的音频资源ID
     */
    Long getNextAudioResourceId();

}
